Skip to content

[py] Update docstrings style #16427

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 6 commits into from
Oct 15, 2025
Merged

[py] Update docstrings style #16427

merged 6 commits into from
Oct 15, 2025
+45 −25

Conversation

iampopovich
Copy link
Contributor

@iampopovich iampopovich commented Oct 14, 2025 •
edited by qodo-merge-pro bot
Loading

User description

🔗 Related Issues

related to #11442

💥 What does this PR do?

This pull request primarily updates docstring formatting in several service classes to follow the Google style, and adjusts the Python linting configuration to better handle docstring-related checks. The changes improve code consistency and maintainability by standardizing documentation and configuring the linter to align with the new style.

Docstring formatting updates:

  • Updated the docstrings in ChromiumService (py/selenium/webdriver/chromium/service.py), Service for Chrome (py/selenium/webdriver/chrome/service.py), Service for WebKitGTK (py/selenium/webdriver/webkitgtk/service.py), and Service for WPEWebKit (py/selenium/webdriver/wpewebkit/service.py) to use Google-style Args: sections instead of the previous :param format. [1] [2] [3] [4]

Linting configuration changes:

  • Modified pyproject.toml to enable docstring checks (D codes) in Ruff, but added extensive ignores for specific docstring rules and set the docstring convention to Google style, ensuring the linter matches the new docstring format.

🔧 Implementation Notes

💡 Additional Considerations

🔄 Types of changes

  • Cleanup (formatting, renaming)

PR Type

Documentation

Description

  • Standardized docstrings to Google style across Python service classes

  • Configured Ruff linter for Google-style docstring convention

  • Added extensive docstring rule ignores in linting configuration

  • Reformatted parameter documentation in Chrome, Chromium, WebKitGTK, and WPEWebKit services

Diagram Walkthrough

flowchart LR
  A["Service Classes"] -- "Convert to Google style" --> B["ChromiumService"]
  A -- "Convert to Google style" --> C["Chrome Service"]
  A -- "Convert to Google style" --> D["WebKitGTK Service"]
  A -- "Convert to Google style" --> E["WPEWebKit Service"]
  F["pyproject.toml"] -- "Configure linter" --> G["Ruff with Google convention"]
Loading

File Walkthrough
Relevant files
Documentation
service.py
Convert Chrome Service docstring to Google style                 

py/selenium/webdriver/chrome/service.py

  • Converted docstring from :param format to Google-style Args: section
  • Reformatted parameter descriptions with proper line wrapping
 +11/-5   
service.py
Convert ChromiumService docstring to Google style               

py/selenium/webdriver/chromium/service.py

  • Converted docstring from :param format to Google-style Args: section
  • Reformatted six parameter descriptions with proper indentation
 +12/-6   
service.py
Convert WebKitGTK Service docstring to Google style           

py/selenium/webdriver/webkitgtk/service.py

  • Converted docstring from :param format to Google-style Args: section
  • Reformatted parameter descriptions for WebKitWebDriver service
 +11/-7   
service.py
Convert WPEWebKit Service docstring to Google style           

py/selenium/webdriver/wpewebkit/service.py

  • Converted docstring from :param format to Google-style Args: section
  • Reformatted parameter descriptions for WPEWebDriver service
 +11/-7   
Configuration changes
pyproject.toml
Configure Ruff linter for Google-style docstrings               

py/pyproject.toml

  • Added D (docstring) checks to Ruff linter configuration
  • Added 17 docstring rule ignores for gradual adoption
  • Set pydocstyle convention to Google style
  • Configured per-file ignores to disable docstring checks by default
 +30/-1   

@selenium-ci selenium-ci added the C-py Python Bindings label Oct 14, 2025
@qodo-merge-pro Qodo Merge Pro
Copy link
Contributor

qodo-merge-pro bot commented Oct 14, 2025 •
edited
Loading

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢
No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪
🎫 No ticket provided
  • Create ticket/issue
Codebase Duplication Compliance
⚪
Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance
⚪
No custom compliance provided

Follow the guide to enable custom compliance check.

  • Update
Compliance status legend 🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

@iampopovich
Copy link
Contributor Author

@cgoldberg review pls
This pull request includes several files manually formatted according to Google's guidelines. I've also added a ruff configuration for the scripts/format.sh script. All Python files in the project will now be ignored, as formatting existing code requires a significant number of changes. I suggest using this configuration for now to migrate to the new docstring style code, then leaving only the necessary RUFF error codes to maintain a consistent code style.

@qodo-merge-pro Qodo Merge Pro
Copy link
Contributor

qodo-merge-pro bot commented Oct 14, 2025 •
edited
Loading

PR Code Suggestions ✨

Explore these optional code suggestions:

CategorySuggestion                                                                                                                                    Impact
Possible issue
✅ Remove global docstring check ignore
Suggestion Impact:The commit removed the per-file ignore for all docstring rules ("*.py" = ["D"]), enabling docstring checks to run.

code diff:

-[tool.ruff.lint.per-file-ignores]
-"*.py" = ["D"]
-

Remove the global ignore rule for docstring (D) checks from pyproject.toml to
ensure the linter can report docstring issues as intended.

py/pyproject.toml [173-174]

 [tool.ruff.lint.per-file-ignores]
-"*.py" = ["D"]

[Suggestion processed]

Suggestion importance[1-10]: 8

__

Why: The suggestion correctly identifies that the per-file-ignores configuration completely negates the enabling of docstring checks, making the primary change of this PR ineffective.

Medium
  • Update

@cgoldberg cgoldberg changed the title [py] Feat/issue 11442 google docstrings py [py] Update docstrings style and add lint rules Oct 14, 2025
@cgoldberg
Copy link
Member

Thanks.. this looks good.

But I don't understand the Ruff rules. This ignores all the docstring linting that you added:

[tool.ruff.lint.per-file-ignores]
"*.py" = ["D"]

Can you also fix the indentation of the extend-ignore rules to match the rest of the file? (4 spaces)

cgoldberg
cgoldberg requested changes Oct 14, 2025
View reviewed changes
Copy link
Member

@cgoldberg cgoldberg left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove [tool.ruff.lint.per-file-ignores]

If this is going to fail everywhere, I'd suggest we don't add any rules until the docstrings are all fixed.

@iampopovich
Copy link
Contributor Author

@cgoldberg The point is that these docstring formatting rules will keep the code up-to-date with Google formatting. If we don't ignore all Python files now, we'll need to make over 200 changes, which could lead to massive conflicts in other developers' branches.
I suggest we fix the formatting manually for now. I'll create a task to add these formatting rules on a permanent basis, and we'll add them a little later.

Thanks.. this looks good.

But I don't understand the Ruff rules. This ignores all the docstring linting that you added:

[tool.ruff.lint.per-file-ignores]
"*.py" = ["D"]

Can you also fix the indentation of the extend-ignore rules to match the rest of the file? (4 spaces)

@iampopovich iampopovich requested a review from cgoldberg October 14, 2025 20:24
cgoldberg
cgoldberg approved these changes Oct 15, 2025
View reviewed changes
Copy link
Member

@cgoldberg cgoldberg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. thanks.

@cgoldberg cgoldberg changed the title [py] Update docstrings style and add lint rules [py] Update docstrings style Oct 15, 2025
@cgoldberg cgoldberg merged commit 65bb55f into SeleniumHQ:trunk Oct 15, 2025
1 check passed
@iampopovich iampopovich mentioned this pull request Oct 15, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cgoldberg cgoldberg cgoldberg approved these changes

Assignees

No one assigned

Labels

C-py Python Bindings Review effort 2/5

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@iampopovich @cgoldberg @selenium-ci